﻿<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head><title>Chastoslov User's Guide</title>
<link  rel="stylesheet" type="text/css" href="main.css" media="all" />
</head><body>

<h1><a name="overview">Overview</a></h1>

<p>Suppose you want to improve your foreign language skills by reading books in this language. Then you probably have to reference a dictionary for the words and phrases you don't know. It may happen too often depending on the text complexity and your language skills thus discouraging you and making you lose your interest. In this case, Chastoslov can give you a help!</p>

<p>This program extracts all distinct words from a text and shows them to you with the number of times they appear in the text. You can learn unknown words (all or just most frequent of them) before reading and make further reading more useful and pleasant.</p>

<p>The program has a handy graphic user's interface that lets you easily upload texts, search words, check/uncheck words, import and export checked words. Multiple users are supported.</p>

<h1><a name="inst">Installation</a></h1>

<p>Chastoslov is created in Java so must work in different operating systems (OS). It was tested in Windows and Linux (Ubuntu), and this guide considers only these two OSs. Still in some other OSs, the program may work too and the instructions may be adapted.</p>

<p>You must have Java Runtime Environment (JRE) to run Chastoslov. The JRE version must be equal to or higher than the version of the Java compiler used for compiling your version of Chastoslov. To know whether JRE is installed and what version it has type in the command line terminal</p>

<pre>java -version</pre>

<p>and you will get something like this</p>

<pre>java version "1.6.0_23"
Java(TM) SE Runtime Environment (build 1.6.0_23-b05)
Java HotSpot(TM) Client VM (build 19.0-b09, mixed mode, sharing)</pre>

<p>So here, the version is 1.6.0_23. If JRE is not installed or has inappropriate version then Chastoslov won't work. In this case you need to install or update JRE. See <a href="http://www.java.com/" target="_blank">Java official page</a> for the instructions.</p>

<p>You get Chastoslov as an archive that contains all necessary files. Extract this archive to the place you want and that's it! The installation is done.</p>

<h1><a name="run">Running</a></h1>

<p>To run Chastoslov in Windows just double-click the file <code>wfguiclient.jar</code>. If it doesn't work you can create a shortcut on your desktop with command </p>

<pre>javaw -jar wfguiclient.jar</pre>

<p>In Linux you can also try to double-click the file <code>wfguiclient.jar</code> or to use the command in the program's directory 

<pre>[user@host wf]$ ./go</pre>

<h1><a name="usage">Usage</a></h1>

<p>The window of the program (see the picture) contains the menu bar that gives you access to all control and adjustment function, the toolbar that provides quicker access to some of these functions and the main working area.</p>

<p><img src="main_window.png" alt="Main window"></p>

<p>Below these elements are discussed in details.</p>

<h2><a name="words">Words</a></h2>

<p>With the filter, you can choose one of the texts and get the words of this text. If you choose <span class="iface">&lt;any text&gt;</span> item then you will get all the words in the program's database regardless the text they belong to. If you choose <span class="iface">&lt;without text&gt;</span> item then you will get the words that do not appear in any of the texts. The small button on the right of the list refreshes the text list. You should use it to see the changes you make to the texts (how to do it &mdash; see below).</p>

<p>Each word in the program may be either checked or unchecked to you. If you consider a word as not interesting for you (you already know it or it's just a mistake of the text processing) you check this word. Otherwise, you leave it unchecked. The filter lets you restrict the word list to only checked words, to only unchecked words or to remove this restriction.</p>

<p>And finally you can find words that contain some substring you want. Just type this substring in the text field. If the text field is empty, it doesn't restrict the words you get.</p>

<p>To apply the filter press the <span class="iface">Refresh</span> button. The filter is not applied automatically after you change the filter parameters.</p> 

<p>When you apply the filter parameters or just start the program the filtered word list appears in the tabular form. At the bottom of the main window you can see the number of words found. Each table row represents the word itself, the word's frequency in the chosen text (or in all texts if <span class="iface">&lt;any text&gt;</span> is chosen) and the state of the word (checked/unchecked). The state is the only field you can change here. Do it by your mouse or by the space button on your keyboard.</p>

<p>The typical usage scenario. You run the program, choose the text you are going to read and see all the words you must learn before the reading. Those words you know you check. Those words you don't know you learn and then check. After all the words, or maybe just most frequent of them, are learnt you start reading the text.</p>

<p><b>Important</b>. The state of a word (checked/unchecked) belongs to the word itself, not to the word in a text. If you check a word in any text then this word will be checked for all other texts (existing and those that will appear later). That's why in the beginning it may take quite much time to check a lot of very simple words. But then when you load another texts those words won't bother you anymore. The list of checked words can be saved to a file and loaded from a file (it's discussed below).</p>

<h2><a name="texts">Texts</a></h2>

<p>A text in Chastoslov doesn't contain words when it's just created. Menu item <span class="iface">Data&rarr;Texts</span> opens the <span class="iface">Texts</span> dialog (see the picture).

<p><img src="texts_dialog.png" alt="Texts dialog"></p>

<p>In this dialog, you can see the text list, edit titles and notes of the texts, add new texts and delete existing ones.</p>

<p>After a text is added, you can upload a text material for it. Prepare your material as a text file and click <span class="iface">Data&rarr;Upload text</span> menu item. The Dialog <span class="iface">Upload text</span> will appear (see the picture).

<p><img src="upload_text_dialog.png" alt="Upload text dialog"></p>

<p>Choose your text, type the full path to your text material (or pick up the file using the <span class="iface">Choose file</span> button), choose the character set of the text and press the <span class="iface">Upload</span> button to start the uploading. It may take some time to complete and this time may be quite long if the text is big enough, but it must be done just once for a text.</p>

<p>If something wrong has happened while text material uploading (wrong character set was chosen and unreadable text is shown in the word list or the system or the program error occurred) you should delete the text material from the text before trying to upload it again. To do it click <span class="iface">Data&rarr;Delete text</span> menu item, choose the text and press the <span class="iface">Delete...</span> button. The words that have been ever uploaded to the program won't be deleted, but after deletion no word will be bound to the text, so you may repeat uploading. 

<h2><a name="imp_exp">Checked words export and import</a></h2>

<p>When you have checked many words, you may want to export/import them from/to the program. It may be needed, for example, for moving the words between different instances of the program or for saving the words before the program reinstallation. The dialogs you need for that are allocated in the <span class="iface">Data</span> menu. The words are exported as a plain word list with one word in one line. No special syntax is used. So the file may be edited and, even more, the import file may be created outside the program.</p>

<h1><a name="users">Users</a></h1>

<p>Chastoslov supports multiple users. All users share all texts and words, but each user has their own set of checked words. It may be used when several people work with one instance of the program.</p>

<p>Just after installation there's only one user whose login is 'wf' and the password is the same. In <span class="iface">Users</span> dialog (<span class="iface">Database&rarr;User</span> menu item) you can specify a more representative name of the current user (will be shown in the title of the main window), create new user and delete current user (i.e. yourself).</p>

<p>How to change current user &mdash; see below.</p>

<h1><a name="conn">Connection</a></h1>

<p>Connection parameters are initially set up so that the only existing user automatically connects to the database. That's why if you use the instance of this program alone and do not demand special security options then you don't need to adjust connection parameters. But if you need to change a user or maybe some other parameters then this section is for you.</p> 

<p>Click <span class="iface">Database&rarr;Connection parameters</span> menu item to open the <span class="iface">Connection parameters</span> dialog. In this dialog, you can choose user's login, enter password and try to connect with these parameters. You must disconnect before you can change the values of the parameters here. If a connection was established successfully, you can save the parameters to cause Chastoslov to use them the next time. If you check <span class="iface">Connect on start</span> check box Chastoslov will try to connect each time when it starts. If you uncheck <span class="iface">Remember password</span> check box this dialog will appear every time you try to connect.</p>

<p>Don't change other parameters in this dialog while the program works correctly. And even if it doesn't, well, it need some skills to know what to do here.</p>

<h1><a name="options">Options</a></h1>

<p>Click <span class="iface">Tools&rarr;Options</span> menu item to open the <span class="iface">Options</span> dialog. There you can change the program's appearance and the interface language.</p>

<h1><a name="troubles">Troubleshooting</a></h1>

<p>This program has proved its stability during several years of use. Anyway, if something goes wrong or you find an issue you can report it at <a href="http://code.google.com/p/chastoslov/" target="_blank">the project's page</a> or just email to the author at <i>stroghov@gmail.com</i>. Please give descriptions of what you did, what the result was and, maybe, what you expected to get. If there's an error message please also include its detailed text.</p>

<p>&nbsp;</p>

</body></html>